Distribuce Python balíčků: Publikování na PyPI a správa verzí

Rozsáhlý ekosystém Pythonu je poháněn obrovskou sbírkou balíčků, které jsou snadno dostupné prostřednictvím Python Package Index (PyPI). Tento průvodce poskytuje komplexní přehled o tom, jak distribuovat vlastní Python balíčky přes PyPI a zajistit tak jejich dostupnost pro vývojáře po celém světě. Prozkoumáme základní nástroje, osvědčené postupy pro správu verzí a pracovní postupy pro vytváření a publikování vysoce kvalitních Python balíčků.

Proč distribuovat svůj Python balíček?

Distribuce vašeho Python balíčku nabízí řadu výhod:

• Sdílení vaší práce: Umožňuje ostatním vývojářům snadno znovu použít váš kód, což podporuje spolupráci a inovace. Představte si globální tým, který používá vaše specializované nástroje pro analýzu dat vytvořené v Pythonu.
• Správa závislostí: Zjednodušuje proces správy závislostí v jiných projektech. Váš balíček lze nainstalovat jediným příkazem, spolu se všemi jeho závislostmi.
• Příspěvek do open-source: Umožňuje vám přispívat do open-source komunity a získat uznání za svou práci. Mnoho klíčových softwarových komponent jsou open-source balíčky udržované vývojáři po celém světě.
• Správa verzí a aktualizace: Poskytuje strukturovaný způsob správy verzí, vydávání aktualizací a oprav chyb. Tím je zajištěno, že uživatelé mají vždy přístup k nejnovější a nejspolehlivější verzi vašeho balíčku.
• Snadná instalace: Zjednodušuje instalaci pro uživatele pomocí `pip install nazev-vaseho-balicku`.

Základní nástroje pro distribuci Python balíčků

Pro vytváření a distribuci Python balíčků je nezbytných několik nástrojů:

• setuptools: Široce používaná knihovna pro definování metadat balíčku, včetně názvu, verze, závislostí a vstupních bodů (entry points). Je to de facto standard pro balení Python projektů.
• wheel: Distribuční formát, který poskytuje efektivnější a spolehlivější proces instalace ve srovnání se zdrojovými distribucemi. Wheel balíčky jsou předkompilované distribuce, které lze nainstalovat bez nutnosti kompilace.
• twine: Nástroj pro bezpečné nahrávání vašeho balíčku na PyPI. Twine šifruje vaše přihlašovací údaje a data balíčku během přenosu, čímž chrání proti odposlechu a útokům typu man-in-the-middle.
• venv/virtualenv: Jsou to nástroje pro vytváření izolovaných Python prostředí. Používání virtuálních prostředí je klíčové pro správu závislostí a předcházení konfliktům mezi různými projekty.

Nastavení vašeho projektu

Než budete moci svůj balíček distribuovat, musíte správně strukturovat svůj projekt.

Příklad struktury projektu

my_package/
├── my_package/
│   ├── __init__.py
│   ├── module1.py
│   └── module2.py
├── tests/
│   ├── __init__.py
│   ├── test_module1.py
│   └── test_module2.py
├── README.md
├── LICENSE
├── setup.py
└── .gitignore

Vysvětlení:

• my_package/: Hlavní adresář obsahující zdrojový kód vašeho balíčku.
• my_package/__init__.py: Činí z adresáře `my_package` Python balíček. Může být prázdný nebo obsahovat inicializační kód.
• my_package/module1.py, my_package/module2.py: Vaše Python moduly obsahující samotný kód.
• tests/: Adresář obsahující vaše jednotkové testy (unit tests). Je klíčové psát testy pro zajištění kvality a spolehlivosti vašeho balíčku.
• README.md: Markdown soubor poskytující popis vašeho balíčku, instrukce k použití a další relevantní informace. To je často první věc, kterou uživatelé na PyPI uvidí.
• LICENSE: Soubor obsahující licenci, pod kterou je váš balíček distribuován (např. MIT, Apache 2.0, GPL). Výběr vhodné licence je zásadní pro specifikaci toho, jak ostatní mohou váš kód používat.
• setup.py: Hlavní konfigurační soubor, který definuje metadata vašeho balíčku a instrukce pro jeho sestavení (build).
• .gitignore: Specifikuje soubory a adresáře, které by měl Git ignorovat (např. dočasné soubory, artefakty sestavení).

Vytvoření souboru `setup.py`

Soubor `setup.py` je srdcem distribuce vašeho balíčku. Obsahuje metadata o vašem balíčku a instrukce pro jeho sestavení a instalaci. Zde je příklad:

import setuptools

with open("README.md", "r") as fh:
    long_description = fh.read()

setuptools.setup(
    name="my_package",  # Nahraďte názvem vašeho balíčku
    version="0.1.0",
    author="Vaše Jméno",  # Nahraďte svým jménem
    author_email="vas.email@priklad.cz", # Nahraďte svým e-mailem
    description="Malý ukázkový balíček",
    long_description=long_description,
    long_description_content_type="text/markdown",
    url="https://github.com/yourusername/my_package", # Nahraďte URL vašeho repozitáře
    packages=setuptools.find_packages(),
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
    python_requires='>=3.6',
    install_requires=[
        "requests", # Příklad závislosti
    ],
)

Vysvětlení:

• name: Název vašeho balíčku, který bude použit na PyPI. Zvolte jedinečný a popisný název.
• version: Číslo verze vašeho balíčku. Dodržujte sémantické verzování (viz níže).
• author, author_email: Vaše jméno a e-mailová adresa.
• description: Krátký popis vašeho balíčku.
• long_description: Delší, podrobnější popis, obvykle načtený z vašeho souboru `README.md`.
• long_description_content_type: Specifikuje formát vašeho dlouhého popisu (např. "text/markdown").
• url: URL domovské stránky vašeho balíčku (např. GitHub repozitář).
• packages: Seznam balíčků, které mají být zahrnuty ve vaší distribuci. `setuptools.find_packages()` automaticky nalezne všechny balíčky ve vašem projektu.
• classifiers: Metadata, která pomáhají uživatelům najít váš balíček na PyPI. Vyberte vhodné klasifikátory ze seznamu Trove Classifiers. Zvažte zahrnutí klasifikátorů pro podporované verze Pythonu, operační systémy a licence.
• python_requires: Specifikuje minimální verzi Pythonu potřebnou k použití vašeho balíčku.
• install_requires: Seznam závislostí, které váš balíček vyžaduje. Tyto závislosti budou automaticky nainstalovány při instalaci vašeho balíčku.

Správa verzí: Sémantické verzování

Sémantické verzování (SemVer) je široce přijímané schéma verzování, které poskytuje jasný a konzistentní způsob komunikace povahy změn ve vašem balíčku.

Číslo verze SemVer se skládá ze tří částí: MAJOR.MINOR.PATCH.

• MAJOR: Zvyšuje se, když provedete nekompatibilní změny v API. To značí významnou změnu, která může vyžadovat, aby uživatelé aktualizovali svůj kód.
• MINOR: Zvyšuje se, když přidáte funkcionalitu zpětně kompatibilním způsobem. To značí nové funkce nebo vylepšení, které nerozbijí existující kód.
• PATCH: Zvyšuje se, když provedete zpětně kompatibilní opravy chyb. Je to pro malé opravy, které nepřidávají nové funkce ani neruší existující funkcionalitu.

Příklady:

• 1.0.0: Počáteční vydání.
• 1.1.0: Přidána nová funkce bez porušení stávajícího kódu.
• 1.0.1: Opravena chyba ve vydání 1.0.0.
• 2.0.0: Provedeny nekompatibilní změny v API.

Používání SemVer pomáhá uživatelům pochopit dopad přechodu na novou verzi vašeho balíčku.

Sestavení vašeho balíčku

Jakmile máte nakonfigurovaný soubor `setup.py`, můžete svůj balíček sestavit.

1. Vytvořte virtuální prostředí: Důrazně doporučujeme vytvořit virtuální prostředí pro izolaci závislostí vašeho balíčku. Použijte `python3 -m venv .venv` (nebo `virtualenv .venv`) a poté jej aktivujte (`source .venv/bin/activate` na Linuxu/macOS, `.venv\Scripts\activate` na Windows).
2. Nainstalujte závislosti pro sestavení: Spusťte `pip install --upgrade setuptools wheel`.
3. Sestavte balíček: Spusťte `python setup.py sdist bdist_wheel`. Tento příkaz vytvoří v adresáři `dist` dva distribuční soubory: zdrojovou distribuci (sdist) a wheel distribuci (bdist_wheel).

`sdist` obsahuje váš zdrojový kód a soubor `setup.py`. `bdist_wheel` je předkompilovaná distribuce, kterou lze nainstalovat rychleji.

Publikování vašeho balíčku na PyPI

Než budete moci svůj balíček publikovat, musíte si vytvořit účet na PyPI (https://pypi.org/) a vytvořit API token. Tento token bude použit k ověření vašich nahrávaných souborů.

1. Zaregistrujte se na PyPI: Přejděte na https://pypi.org/account/register/ a vytvořte si účet.
2. Vytvořte API token: Přejděte na https://pypi.org/manage/account/, sjeďte dolů do sekce "API tokens" a vytvořte nový token. Tento token si bezpečně uložte, protože ho budete potřebovat k nahrání balíčku.
3. Nainstalujte Twine: Spusťte `pip install twine`.
4. Nahrajte svůj balíček: Spusťte `twine upload dist/*`. Budete vyzváni k zadání uživatelského jména (`__token__`) a hesla (API token, který jste vytvořili).

Důležitá bezpečnostní poznámka: Nikdy necommitujte svůj API token do repozitáře. Ukládejte ho bezpečně a pro přístup k němu během procesu nahrávání používejte proměnné prostředí nebo jiné bezpečné metody.

Testování instalace vašeho balíčku

Po publikování balíčku je nezbytné otestovat, zda jej lze správně nainstalovat.

1. Vytvořte nové virtuální prostředí: Tím zajistíte, že testujete instalaci v čistém prostředí.
2. Nainstalujte svůj balíček: Spusťte `pip install nazev-vaseho-balicku`.
3. Importujte a použijte svůj balíček: V Python interpretu importujte svůj balíček a ověřte, že funguje podle očekávání.

Kontinuální integrace a kontinuální nasazování (CI/CD)

Pro automatizaci procesu sestavování, testování a publikování vašeho balíčku můžete použít CI/CD nástroje, jako jsou GitHub Actions, GitLab CI nebo Travis CI.

Zde je příklad workflow pro GitHub Actions, který sestaví a publikuje váš balíček na PyPI:

name: Publikovat na PyPI

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Nastavit Python 3.x
      uses: actions/setup-python@v2
      with:
        python-version: 3.x
    - name: Nainstalovat závislosti
      run: |
        python -m pip install --upgrade pip
        pip install setuptools wheel twine
    - name: Sestavit balíček
      run: python setup.py sdist bdist_wheel
    - name: Publikovat balíček na PyPI
      run: |
        twine upload dist/* \
          -u __token__ \
          -p ${{ secrets.PYPI_API_TOKEN }}

Vysvětlení:

• Tento workflow se spustí, když je na GitHubu publikováno nové vydání (release).
• Stáhne kód, nastaví Python, nainstaluje závislosti, sestaví balíček a nahraje ho na PyPI.
• secrets.PYPI_API_TOKEN je GitHub secret, který ukládá váš PyPI API token. Tento secret musíte nakonfigurovat v nastavení vašeho GitHub repozitáře.

Osvědčené postupy pro distribuci Python balíčků

• Pište komplexní dokumentaci: Zahrňte podrobný soubor `README.md` a také API dokumentaci pomocí nástrojů jako Sphinx. Jasná a úplná dokumentace je klíčová pro snadné použití vašeho balíčku.
• Pište jednotkové testy (unit tests): Důkladně testujte svůj kód, abyste zajistili jeho kvalitu a spolehlivost. Použijte testovací framework jako pytest nebo unittest.
• Dodržujte stylistické směrnice PEP 8: Držte se style guidu Python Enhancement Proposal 8 (PEP 8), abyste zajistili konzistentní a čitelný kód.
• Použijte licenci: Zvolte vhodnou open-source licenci, abyste specifikovali, jak ostatní mohou používat váš kód.
• Udržujte své závislosti aktuální: Pravidelně aktualizujte závislosti vašeho balíčku, abyste těžili z oprav chyb, bezpečnostních záplat a nových funkcí.
• Používejte virtuální prostředí: Vždy vyvíjejte a testujte svůj balíček ve virtuálním prostředí, abyste izolovali závislosti.
• Zvažte internacionalizaci (i18n) a lokalizaci (l10n): Pokud váš balíček zpracovává text nebo data určená pro uživatele, zvažte jeho přizpůsobení různým jazykům a regionům. Tím se celosvětově rozšíří vaše potenciální uživatelská základna. S tím mohou pomoci nástroje jako Babel.
• Zpracovávejte různá časová pásma a měny: Pokud váš balíček pracuje s daty, časy nebo finančními transakcemi, pamatujte na různá časová pásma a měny po celém světě. Pro správné zvládnutí těchto složitostí použijte vhodné knihovny a API.
• Poskytujte jasné chybové zprávy: Pište informativní chybové zprávy, které uživatelům pomohou pochopit, co se pokazilo a jak to opravit. Pokud je to možné, přeložte tyto chybové zprávy do různých jazyků.
• Myslete na přístupnost: Při navrhování rozhraní a dokumentace vašeho balíčku zvažte uživatele se zdravotním postižením. Dodržujte pokyny pro přístupnost, abyste zajistili, že váš balíček bude použitelný pro všechny.

Pokročilá témata

• Jmenné prostory balíčků (Namespace packages): Umožňují rozdělit jeden Python balíček do více adresářů nebo dokonce do více distribucí.
• Vstupní body (Entry points): Umožňují definovat funkce nebo třídy, které lze volat z jiných balíčků nebo z příkazového řádku.
• Datové soubory: Umožňují zahrnout do vaší distribuce i jiné než Python soubory (např. datové soubory, konfigurační soubory).
• Podmíněné závislosti: Umožňují specifikovat závislosti, které jsou vyžadovány pouze za určitých podmínek (např. na konkrétním operačním systému).

Závěr

Distribuce vašeho Python balíčku na PyPI je skvělý způsob, jak sdílet svou práci se světem a přispět do ekosystému Pythonu. Dodržováním kroků a osvědčených postupů uvedených v tomto průvodci můžete vytvářet a publikovat vysoce kvalitní Python balíčky, které se snadno instalují, používají a udržují. Nezapomeňte klást důraz na jasnou dokumentaci, důkladné testování a konzistentní správu verzí, abyste zajistili úspěch vašeho balíčku.